<?php
/*
 * Copyright (C) 2010 TopCoder Inc., All Rights Reserved.
 */
namespace protocol\translation\framework\services\mms;

/**
 * <p>
 * The MMS service interface creates the One API sms service REST interface as defined
 * in the attached specification.
 * </p>
 *
 * <p>
 * It has one method for each REST request type. Recess framework is used to map REST
 * requests to PHP methods making simple PHP methods REST aware.
 * </p>
 *
 * <p>
 * Thread Safety: Implementations are not required to be thread-safe.
 * </p>
 *
 * @author hpana, akinwale
 * @version 1.0
 */
interface MMS_Service {
    /**
     * <p>
     * Sends an MMS message to one or more mobile terminals.
     * </p>
     *
     * <p>
     * The method will have the following Recess annotation.
     * Each annotation is bound directly to one method argument. Recess framework will automatically
     * bind these parameters extracted from the equest url, when a REST request is received to this
     * method annotated configuration url.
     * </p>
     *
     * @annotations:
     * @!Route POST, /$api_version/messaging/outbound/$sender_address/requests&carrier=$carrier
     *
     * @param string $api_version the API version
     * @param string $senderAddress the sender address
     * @param string $carrier the carrier to process the request
     *
     * @throws IllegalArgumentException if any argument is not of expected type or if it is not set or empty
     * @throws RequestProcessingException if any errors occur during processing
     */
    public function sendMessage($api_version, $senderAddress, $carrier);

    /**
     * <p>
     * Queries the delivery status of an MMS.
     * </p>
     *
     * <p>
     * The method will have the following Recess annotation.
     * Each annotation is bound directly to one method argument. Recess framework will automatically
     * bind these parameters extracted from the equest url, when a REST request is received to this
     * method annotated configuration url.
     * </p>
     *
     * @annotations:
     * @!Route GET, /$api_version/messaging/outbound/requests/$sender_address/$request_id/deliveryinfo&carrier=$carrier
     *
     * @param string $api_version the API version
     * @param string $senderAddress the sender address
     * @param string $carrier the carrier to process the request
     *
     * @throws IllegalArgumentException if any argument is not of expected type or if it is not set or empty
     * @throws RequestProcessingException if any errors occur during processing
     */
    public function queryMessage($api_version, $senderAddress, $carrier);

    /**
     * <p>
     * Subscribes the user to MMS delivery notification.
     * </p>
     *
     * <p>
     * The method will have the following Recess annotation.
     * Each annotation is bound directly to one method argument. Recess framework will automatically
     * bind these parameters extracted from the equest url, when a REST request is received to this
     * method annotated configuration url.
     * </p>
     *
     * @annotations:
     * @!Route POST, /$api_version/messaging/outbound/$sender_address/subscriptions&carrier=$carrier
     *
     * @param string $api_version the API version
     * @param string $senderAddress the sender address
     * @param string $carrier the carrier to process the request
     *
     * @throws IllegalArgumentException if any argument is not of expected type or if it is not set or empty
     * @throws RequestProcessingException if any errors occur during processing
     */
    public function subscribeToMMSDeliveryNotifications($api_version, $senderAddress, $carrier);

    /**
     * <p>
     * Stops the subscription of the user to MMS delivery notifications. Unsubscribes the user.
     * </p>
     *
     * <p>
     * The method will have the following Recess annotation.
     * Each annotation is bound directly to one method argument. Recess framework will automatically
     * bind these parameters extracted from the equest url, when a REST request is received to this
     * method annotated configuration url.
     * </p>
     *
     * @annotations:
     * @!Route DELETE, /$api_version//messaging/outbound/subscriptions/$subscriptionId/carrier=$carrier
     *
     * @param string $api_version the API version
     * @param int $subscription_id the subscription ID
     * @param string $carrier the carrier to process the request
     *
     * @throws IllegalArgumentException if any argument is not of expected type or if it is not set or empty
     * @throws RequestProcessingException if any errors occur during processing
     */
    public function stopSubscriptionToMMSDeliveryNotifications($api_version, $subscription_id, $carrier);

    /**
     * <p>
     * This method retrieves the messages sent to the web application.
     * </p>
     *
     * <p>
     * The method will have the following Recess annotation.
     * Each annotation is bound directly to one method argument. Recess framework will automatically
     * bind these parameters extracted from the equest url, when a REST request is received to this
     * method annotated configuration url.
     * </p>
     *
     * @annotations:
     * @!Route GET, /$api_version/messaging/inbound/registrations/$registration_id/messages&carrier=$carrier
     *
     * @param string $api_version tbe API version
     * @param int $registration_id the registration ID
     * @param string $carrier the carrier to process the request
     *
     * @throws IllegalArgumentException if any argument is not of expected type or if it is not set or empty
     * @throws RequestProcessingException if any errors occur during processing
     */
    public function retrieveMessages($api_version, $registration_id, $carrier);

    /**
     * <p>
     * Subscribes to notifications of messages sent to the user application.
     * </p>
     *
     * <p>
     * The method will have the following Recess annotation.
     * Each annotation is bound directly to one method argument. Recess framework will automatically
     * bind these parameters extracted from the equest url, when a REST request is received to this
     * method annotated configuration url.
     * </p>
     *
     * @annotations:
     * @!Route POST, /$api_version/messaging/inbound/subscriptions&carrier=$carrier
     *
     * @param string $api_version the API version
     * @param string $senderAddress the sender address
     * @param string $carrier the carrier to process the request
     *
     * @throws IllegalArgumentException if any argument is not of expected type or if it is not set or empty
     * @throws RequestProcessingException if any errors occur during processing
     */
    public function subscribeToNotifications($api_version, $senderAddress, $carrier);

    /**
     * <p>
     * Stops the subscription of the user to MMS delivery notification. Unsubscribes the user.
     * </p>
     *
     * <p>
     * The method will have the following Recess annotation.
     * Each annotation is bound directly to one method argument. Recess framework will automatically
     * bind these parameters extracted from the equest url, when a REST request is received to this
     * method annotated configuration url.
     * </p>
     *
     * @annotations:
     * @!Route DELETE, /$api_version/messaging/inbound/subscriptions/$subscription_id
     *
     * @param string $api_version the API version
     * @param int $subscriptionId the subscription ID
     * @param string $carrier the carrier to process the request
     *
     * @throws IllegalArgumentException if any argument is not of expected type or if it is not set or empty
     * @throws RequestProcessingException if any errors occur during processing
     */
    public function stopSubscriptionToNotifications($api_version, $subscriptionId, $carrier);

    /**
     * <p>
     * Verifies if initialization is successful and that class can execute business methods.
     * </p>
     *
     * <p>
     * Checks that $_converter and $_protocolClient are of appropriate type and initialized
     * and that $_converter is of type SMPP_JSON_Convertor.
     * </p>
     *
     * @throws InvalidStateException if the class is not initialized fully.
     */
    public function checkInitialization();
}

?>